SDK数据定义文档（API-STRUCT/ENUM/DEFINE）

硬件SDKV6（Xlink Device SDKV6）相关 API-STRUCT/ENUM/DEFINE（结构体/枚举/宏定义）接口及说明如下：

1. 结构体 STRUCT

1.1. SDK实例 xlink_sdk_instance_t

typedef struct xlink_sdk_instance{
    xlink_uint8* dev_pid;
	xlink_uint8* dev_pkey;
	xlink_uint8 dev_mac[XLINK_DEV_MAC_LENGTH_MAX];
	xlink_uint8  dev_mac_length;
	xlink_uint8  dev_name[XLINK_DEV_NAME_MAX + 1];
	xlink_uint16 dev_firmware_version;
	xlink_uint16 mcu_firmware_version;
	xlink_uint8  cloud_enable;
	xlink_uint8  local_enable;
	xlink_uint8* certificate_id;
	xlink_int16 certificate_id_length;
	xlink_uint8* certificate_key;
	xlink_int16 certificate_key_length;
	xlink_uint8* cloud_rec_buffer;
	xlink_int16 cloud_rec_buffer_length;
	xlink_uint8 log_level;
    xlink_uint8 log_enable;
	xlink_uint8 sdk_para[XLINK_SDK_PARA_LENGTH];
	xlink_uint16 dev_sn_length;
	xlink_uint8 *dev_sn;
	xlink_uint16 pingcode_length;
	xlink_uint8 *pingcode;
	xlink_uint32 identify;
} xlink_sdk_instance_t;

描述

成员 说明
*dev_pid 产品ID
*dev_pkey 产品KEY
dev_mac 设备MAC地址
dev_mac_length 设备MAC长度
dev_name 设备名称，最长为XLINK_DEV_NAME_MAX字节
dev_firmware_version 固件版本
cloud_enable 1使用外网，0不使用外网
local_enable 1使用内网，0不使用内网
certificate_id 用户名称
certificate_id_length 用户名称长度
certificate_key 用户密码
certificate_key_length 用户密码长度
*cloud_rec_buffer 外网接收数据缓存区，默认大小2049bytes
cloud_rec_buffer_length 外网接收数据缓存区大小
log_level 0:DEBUG 1:INFO 2:WARN 3:ERROR
log_enable 0:不使能，1:使能
sdk_para sdk使用内存区域，用户不能修改，否则会导致错误
dev_sn_length sn码长度，如没有sn码，请确保此值为0
*dev_sn sn码
pingcode_length pingcode码，如没有sn码，请确保此值为0
*pingcode pingcode码
*identify 标识码

1.2. 设备连接状态：xlink_status_t

typedef struct xlink_status{
	xlink_uint8 status;
} xlink_status_t;

描述

status 说明
0 连接失败
1 上线成功
2 用户需要断开连接，停止重连操作

1.3. 日期事件：xlink_datetime_t

typedef struct xlink_datetime{
	xlink_uint16 year;
	xlink_uint8  month;
	xlink_uint8  day;
	xlink_uint8  week;
	xlink_uint8  hour;
	xlink_uint8  min;
	xlink_uint8  second;
	xlink_int16  zone;
} xlink_datetime_t;

描述

成员 说明
year 年
month 月
day 日
week 周
hour 时
min 分
second 秒
zone 时区

1.4. 升级：xlink_upgrade_t

typedef struct xlink_upgrade{
	xlink_int32  device_id;
	xlink_uint8   flag;
	xlink_uint16 firmware_version;
	xlink_uint32 file_size;
	xlink_uint8*  url;
	xlink_int16  url_length;
	xlink_uint8*  hash;
	xlink_int16  hash_length;
} xlink_upgrade_t;

描述

成员 说明
device_id 设备ID
flag bit7:代表wifi升级，1有效，bit6:保留，bit5:代表强制升级，1有效，其他保留
firmware_version 固件新版本
file_size 文件大小
*url 文件下载链接
url_length 文件下载链接长度
*hash hash校验码
hash_length hash校验码长度

1.5. 升级完成：xlink_upgrade_complete_t

typedef struct xlink_upgrade_complete{
	xlink_uint8   flag;
	xlink_uint8   status;
	xlink_uint16 last_version;
	xlink_uint16 current_version;
} xlink_upgrade_complete_t;

描述

成员 说明
flag bit7:wifi升级，1有效，其他保留
status 1表示成功，2表示失败
last_version 升级前的固件版本
current_version 升级后新的固件版本

1.6. 请求响应：xlink_request_cb_t

typedef struct xlink_response_cb{
	xlink_uint16  messageid;
	xlink_uint32 value;
} xlink_response_cb_t;

描述

成员 说明
messageid 对应发送的消息ID
value 0：成功，1：失败，其他保留

1.7. SDK消息：xlink_sdk_notify_t

typedef struct xlink_sdk_notify{
	xlink_uint8 from_type;
	xlink_int32 from_id;
	xlink_uint8* message;
	xlink_int16 message_length;
} xlink_sdk_notify_t;

描述

成员 说明
from_type 消息来自哪个设备，1:server,2:devcie,3:app,其他保留
from_id 设备ID
*message 消息内容
message_length 消息内容长度

1.8. SDK事件：xlink_sdk_event_t

typedef struct xlink_sdk_event{
	xlink_event_type_t event_type_t;
	xlink_union {
		xlink_status_t status;
		xlink_sub_ret_t ret;
		xlink_datetime_t datetime_t;
		xlink_upgrade_t upgrade_t;
		xlink_upgrade_complete_t upgrade_complete_t;
		xlink_request_cb_t request_cb_t;
		xlink_sdk_notify_t notify_t;
		xlink_ask_device_ota_package_t ask_device_ota_package_t;
		xlink_ota_task_check_package_t ota_task_check_package_t;
		xlink_ota_task_check_ack_package_t ota_task_check_ack_package_t;
		xlink_ota_report_upgrade_result_package_t ota_report_upgrade_result_package_t;
	#if PRODUCTION_TEST_ENABLE
		xlink_pdct_cb_t pdct_cb_t;
	#endif
	}event_struct_t;
} xlink_sdk_event_t;

描述

成员 说明
enum_event_type_t 事件类型
event_struct_t 事件数据

1.9. 位置信息上报：xlink_location_t

typedef struct xlink_location {
    xlink_double longitude;
    xlink_double latitude;
    xlink_uint64 timestamp;
    xlink_uint8 timestamp_flag;
    xlink_uint16 address_length;
    xlink_uint8 *address;
} xlink_location_t;

描述

成员 说明
longitude 经度
latitude 纬度
timestamp 时间戳
timestamp_flag 时间戳标志，如不需要上传时间戳，确保此值为0
address_length 地址长度（最大值500），如不需要上传地址，确保此值为0
*address 地址信息

1.10. 产测事件结构体：xlink_pdct_cb_t

typedef struct xlink_pdct_cb {
    xlink_pdct_event_type pdct_event_t;
    xlink_production_event_msgtype result_message;
}xlink_pdct_cb_t;

描述

成员 说明
pdct_event_t 产测事件类型
result_message 产测事件携带的消息

1.11. 设备订阅返回：xlink_sub_ret_t

typedef struct xlink_sub_ret{
	xlink_uint8 status;
} xlink_sub_ret_t;

描述

status 说明
0 订阅失败
1 订阅成功

2. 枚举 ENUM

2.1. SDK 事件类型：xlink_event_type_t

typedef enum {
	EVENT_TYPE_STATUS = 0,
	EVENT_TYPE_REQ_DATETIME,
	EVENT_TYPE_REQ_DATETIME_CB,
	EVENT_TYPE_UPGRADE_CB,
	EVENT_TYPE_UPGRADE_COMPLETE,
	EVENT_TYPE_REQUEST_CB,
	EVENT_TYPE_NOTIFY,
	EVENT_TYPE_PRODUCTION_TEST,
	EVENT_TYPE_SERVER_ASK_DEVICE_OTA,
	EVENT_TYPE_CHECK_OTA_TASK,
	EVENT_TYPE_CHECK_OTA_TASK_CB,
	EVENT_TYPE_REPORT_OTA_UPGRADE_RESULT,
    EVENT_TYPE_SUB_RET
} xlink_enum_event_type_t;

描述

成员 说明
EVENT_TYPE_CONNECT_STATION 设备连接服务器的连接状态事件类型，对应结构体 xlink_connect_station_t
EVENT_TYPE_REQ_DATETIME 设备请求获取服务器时间事件类型，事件内容为NULL，请求数据间隔不能大于60秒一次
EVENT_TYPE_REQ_DATETIME_CB 设备请求服务器时间返回事件类型，对应结构体为 xlink_datetime_t
EVENT_TYPE_UPGRADE_CB 设备收到服务器推送的升级事件类型，对应结构体为 xlink_upgrade_t
EVENT_TYPE_UPGRADE_COMPLETE 设备升级完成后上报给服务器事件类型，对应结构体为 xlink_upgrade_complete_t
EVENT_TYPE_REQUEST_CB 设备发送数据后收到的应答事件类型，对应结构体为 xlink_request_cb_t
EVENT_TYPE_NOTIFY_CB 消息通知
EVENT_TYPE_PRODUCTION_TEST 产测事件类型，对应结构体为xlink_pdct_cb_t
EVENT_TYPE_SERVER_ASK_DEVICE_OTA 服务器/APP要求设备进行OTA升级事件类型，对应结构体为 xlink_ota_from_type_t xlink_ask_device_ota_package_t
EVENT_TYPE_CHECK_OTA_TASK 设备向服务器/APP请求查询OTA升级任务事件类型，对应结构体为 xlink_ota_task_check_package_t
EVENT_TYPE_CHECK_OTA_TASK_CB 设备收到服务器/APP请求查询OTA升级任务的返回事件类型，对应结构体为 xlink_enum_ota_check_ack_code_t xlink_ota_task_check_ack_package_t
EVENT_TYPE_REPORT_OTA_UPGRADE_RESULT 设备升级完成后上报服务器/APP事件类型（拓展具有taskid/identify），对应结构体为 xlink_ota_report_upgrade_result_package_t
EVENT_TYPE_SUB_RET 设备订阅返回事件，对应结构体xlink_sub_ret_t

2.2. 产测事件类型：xlink_pdct_event_type

typedef xlink_enum{
    EVENT_TYPE_ENTER_PDCT_TEST_SUCCESS = 0,
    EVENT_TYPE_ENTER_PDCT_TEST_FAIL,
    EVENT_TYPE_PDCT_TEST_END_SUCCESS,
    EVENT_TYPE_PDCT_TEST_END_FAIL,
} xlink_pdct_event_type;

描述

成员 说明
EVENT_TYPE_ENTER_PDCT_TEST_SUCCESS 产测开始成功
EVENT_TYPE_ENTER_PDCT_TEST_FAIL 产测开始失败
EVENT_TYPE_PDCT_TEST_END_SUCCESS 产测结束成功
EVENT_TYPE_PDCT_TEST_END_FAIL 产测结束失败

2.3. 产测事件类型：xlink_production_event_msgtype

typedef xlink_enum {
    XLINK_PRODUCTION_START_SUCCESS = 0,
    XLINK_PRODUCTION_START_FAIL_DEVIDE_OFFLINE,
    XLINK_PRODUCTION_START_FAIL_PRODUCTION_TEST_DISABLE,
    XLINK_PRODUCTION_END_SUCCESS,
    XLINK_PRODUCTION_END_FAIL
}xlink_production_event_msgtype;

描述

成员 说明
XLINK_PRODUCTION_START_SUCCESS 产测开始成功
XLINK_PRODUCTION_START_FAIL_DEVIDE_OFFLINE 产测开始失败，设备未上线
XLINK_PRODUCTION_START_FAIL_PRODUCTION_TEST_DISABLE 产测开始失败，未使能产测
XLINK_PRODUCTION_END_SUCCESS 产测结束成功
XLINK_PRODUCTION_END_FAIL 产测结束失败

3. 宏定义 #define

3.1. 数据类型定义

宏 定义
xlink_int8 char
xlink_uint8 unsigned char
xlink_int16 short
xlink_uint16 unsigned short
xlink_int32 int
xlink_uint32 unsigned int
xlink_int64 long long
xlink_uint64 unsigned long long
xlink_double double
xlink_null NULL
xlink_enum enum
xlink_union union
xlink_memcpy memcpy
xlink_memset memset
xlink_memcmp memcmp
xlink_sizeof sizeof
xlink_strlen strlen
xlink_sprintf sprintf
xlink_snprintf snprintf
xlink_strcpy strcpy
xlink_strncpy strncpy
xlink_strcmp strcmp
xlink_strchr strchr
xlink_strstr strstr
xlink_printf printf

3.2. 参数定义

宏 定义 说明
宏 定义 说明
XLINK_DEV_MAC_LENGTH_MIN 1 最小MAC地址长度
XLINK_DEV_MAC_LENGTH_MAX 32 最长MAC地址长度
XLINK_SYS_PARA_LENGTH (1024*3) SDK参数空间大小
XLINK_PACKET_LENGTH_MAX 1000 上报数据端点内容最大长度
XLINK_LOCAL_PAIRING_SEED_MAX 16 配对最大次数
XLINK_LOCAL_PAIRING_MAX_TIMES 65536 配对最长时间
PRODUCTION_TEST_ENABLE 1 产测功能开启
SDK_PROTOCOL_VERSION 6 SDK 协议版本
define SDK_MASTER_VERSION 6220 SDK版本
XLINK_DISCOVER_ENABLE 1 SDK发现开启
MQTT_VERSION 3 MQTT协议版本
XLINK_DEV_NAME_MAX 16 设备名称最大长度

3.3. SDK连接状态定义

宏 定义 说明
EVENT_DISCONNECTED_SERVER 0 服务器断开连接
EVENT_CONNECTED_SERVER 0 设备上线成功
EVENT_SERVER_REJECT_DEVICE_REQUEST 2 禁止重连状态
没找到需要的文档？
你可以提交工单反馈 或 阅读常见问题
客服工单常见问题